import {Layout} from '../../src/Layout';
export default Layout;

import {TimeField} from '@react-spectrum/s2';
import docs from 'docs:@react-spectrum/s2';

export const tags = ['date', 'input'];
export const description = 'Allows a user to enter and edit time values using a keyboard.';

# TimeField

<PageDescription>{docs.exports.TimeField.description}</PageDescription>

<VisualExample
  component={TimeField}
  docs={docs.exports.TimeField}
  links={docs.links}
  props={['label', 'granularity', 'size', 'labelPosition', 'description', 'contextualHelp', 'isDisabled']}
  initialProps={{label: 'Event time'}}
  importSource="@react-spectrum/s2"
  type="s2" />

## Value

Use the `value` or `defaultValue` prop to set the time value, using objects in the [@internationalized/date](react-aria:internationalized/date/) package. `TimeField` accepts plain [Time](react-aria:internationalized/date/Time), [CalendarDateTime](react-aria:internationalized/date/CalendarDateTime), or [ZonedDateTime](react-aria:internationalized/date/ZonedDateTime), but only displays the time.

```tsx render
"use client";
import {Time} from '@internationalized/date';
import {TimeField} from '@react-spectrum/s2';
import {useState} from 'react';

function Example() {
  let [time, setTime] = useState(new Time(11, 45));
  
  return (
    <>
      <TimeField
        ///- begin highlight -///
        value={time}
        onChange={setTime} />
      {/*- end highlight -*/}
      <p>Selected time: {time ? time.toString() : '--'}</p>
    </>
  );
}
```

### Format options

The time format is automatically determined based on the user's locale. `TimeField` supports several props to control how values are displayed.

```tsx render docs={docs.exports.TimeField} links={docs.links} props={['granularity', 'hourCycle', 'hideTimeZone', 'shouldForceLeadingZeros']} initialProps={{label: 'Time'}} type="s2"
"use client";
import {parseZonedDateTime} from '@internationalized/date';
import {TimeField} from '@react-spectrum/s2';

<TimeField
  /* PROPS */
  defaultValue={parseZonedDateTime('2025-02-03T17:45:00[America/Los_Angeles]')} />
```

## Forms

Use the `name` prop to submit the selected date to the server as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string. Set the `isRequired`, `minValue`, or `maxValue` props to validate the value, or implement custom client or server-side validation. See the [Forms](forms) guide to learn more.

```tsx render docs={docs.exports.TextField} links={docs.links} props={['isRequired', 'necessityIndicator']} initialProps={{isRequired: true}} type="s2" wide
"use client";
import {Time} from '@internationalized/date';
import {TimeField, Form, Button} from '@react-spectrum/s2';

function Example(props) {
  return (
    <Form>
      <TimeField
        {...props}
        label="Appointment time"
        ///- begin highlight -///
        name="time"
        /* PROPS */
        minValue={new Time(9)}
        maxValue={new Time(17)}
        validate={time => time?.minute % 15 !== 0 ? 'Appointments start every 15 minutes.' : null}
        ///- end highlight -///
      />
      <Button type="submit">Submit</Button>
    </Form>
  );
}
```

## API

<PropTable component={docs.exports.TimeField} links={docs.links} />
